package me.flyray.bsin.facade.engine;

import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import me.flyray.bsin.domain.entity.Wallet;
import me.flyray.bsin.domain.entity.WalletAccount;
import me.flyray.bsin.domain.request.WalletDTO;
import me.flyray.bsin.domain.response.WalletVO;

import java.util.Map;

/**
 * Wallet钱包服务引擎接口
 * 
 * 功能概述：
 * 基于PassCard会员卡的TBA钱包管理系统，是整个身份体系的资产层
 * 
 * 架构关系：
 * - 基础层：DID（去中心化身份标识）
 * - 档案层：Profile（身份档案）1:1 映射DID
 * - 会员层：PassCard（品牌会员卡）1:N 关联Profile
 * - 资产层：Wallet（本接口管理的TBA钱包）1:1 绑定PassCard
 * - 应用层：Agent（基于钱包的AI数字分身服务）
 * 
 * 核心概念：
 * - TBA钱包：基于ERC6551标准的Token Bound Account
 * - 自动生成：每张PassCard开卡时自动创建独立钱包
 * - 多链支持：支持以太坊、BSC、Polygon等主流区块链
 * - 资产隔离：每个钱包独立管理，确保资产安全
 * 
 * 业务流程：
 * 1. 前置条件：用户已开通PassCard会员卡
 * 2. 系统自动为PassCard生成TBA钱包地址
 * 3. 钱包支持多种数字资产的存储和转账
 * 4. 集成DeFi协议，提供金融服务能力
 * 5. 支持权益分红的自动到账
 * 
 * 技术特点：
 * - ERC6551 TBA技术，NFT即钱包
 * - 多重签名和风控机制
 * - 支持MPC（多方计算）钱包
 * - 与PassCard会员权益深度绑定
 * 
 * @author bolei
 * @date 2023/6/26 13:51
 * @desc Wallet钱包服务引擎 - 身份体系的资产层
 */

public interface WalletServiceEngine {

    /**
     * 创建链上钱包账户
     * 
     * 功能说明：
     * - 为PassCard会员卡创建对应的链上钱包
     * - 支持多种区块链网络的钱包创建
     * - 与PassCard的TBA地址进行关联
     * 
     * 架构位置：资产层的核心功能
     * 依赖关系：需要已存在的PassCard会员卡
     * 
     * @param requestMap 创建参数，包含PassCard信息和链配置
     * @return Map 钱包创建结果，包含地址和状态
     * @throws Exception 创建过程中的异常
     */
    Map<String, Object> createWalletAccount(Map<String, Object> requestMap) throws Exception;

    /**
     * 导入钱包
     *
     * 功能说明：
     * - 导入用户已有的区块链钱包
     * - 支持多种区块链网络和钱包类型
     * @param walletReq 导入参数，包含钱包信息:私钥，地址，密码等
     * @return Map 钱包导入结果，包含地址和状态
     * @throws Exception 导入过程中的异常
     */
    Wallet importWallet(Wallet walletReq) throws Exception;


    /**
     * 创建钱包
     *
     *
     * 创建流程：
     * 1. 数据校验：验证钱包参数合法性
     * 2. 保存钱包信息：录入钱包基础信息
     * 3. 币种账户配置：
     *    - 默认钱包：根据客户设置创建多币种账户
     *    - 自定义钱包：只创建环境本币账户
     *    - 商户钱包： 商户平台默认钱包账户
     *
     * @param walletReq 钱包创建请求对象
     * @return Wallet 创建成功的钱包实体
     */
    public Wallet createWallet(Wallet walletReq) throws Exception;

    /**
     * 创建MPC多方计算钱包
     * 
     * 功能说明：
     * - 创建基于MPC技术的企业级安全钱包
     * - 支持多重签名和分布式密钥管理
     * - 根据钱包类型自动配置币种账户
     * 
     * 创建流程：
     * 1. 数据校验：验证钱包参数合法性
     * 2. 保存钱包信息：录入钱包基础信息
     * 3. 币种账户配置：
     *    - 默认钱包：根据客户设置创建多币种账户
     *    - 自定义钱包：只创建环境本币账户
     * 4. 链上地址生成：创建实际的区块链地址
     * 
     * @param walletReq 钱包创建请求对象
     * @return Wallet 创建成功的钱包实体
     */
    public Wallet createMPCWallet(Wallet walletReq);

    /**
     * 钱包资产提现
     * 
     * 功能说明：
     * - 从TBA钱包提现数字资产到外部地址
     * - 支持多种代币和NFT的提现操作
     * - 集成风控检查和合规验证
     * 
     * 提现流程：
     * 1. 验证PassCard身份和权限
     * 2. 检查钱包余额和提现限额
     * 3. 执行风控和合规检查
     * 4. 调用智能合约执行提现
     * 5. 记录交易日志和状态更新
     * 
     * @param walletDTO 提现请求参数，包含金额、目标地址等
     */
    public void withdraw(WalletDTO walletDTO);

    /**
     * 分页查询钱包列表
     * 
     * 功能说明：
     * - 查询用户或租户下的所有钱包
     * - 支持按钱包类型、状态等条件筛选
     * - 显示钱包余额、交易记录等信息
     * 
     * 查询维度：
     * - 按用户ID查询个人钱包
     * - 按租户ID查询企业钱包
     * - 按PassCard关联查询会员钱包
     * 
     * @param walletDTO 查询参数，包含分页和筛选条件
     * @return Page<WalletVO> 分页钱包列表
     */
    public Page<WalletVO> getPageList(WalletDTO walletDTO);

    /**
     * 编辑钱包配置
     * 
     * 功能说明：
     * - 修改钱包的配置信息和状态
     * - 支持钱包冻结/解冻操作
     * - 批量管理钱包下的所有地址状态
     * 
     * 状态管理：
     * - 钱包冻结：钱包下所有地址变为禁用状态
     * - 钱包激活：恢复钱包和地址的正常使用
     * - 风控调整：修改交易限额和风控规则
     * 
     * @param walletDTO 编辑参数，包含钱包ID和新的配置
     */
    public void edit(WalletDTO walletDTO);

    /**
     * 删除钱包
     * 
     * 功能说明：
     * - 安全删除用户钱包和相关数据
     * - 确保资产转移完成后才能删除
     * - 保留必要的审计日志
     * 
     * 删除前检查：
     * 1. 验证钱包余额为零
     * 2. 确认无待处理交易
     * 3. 检查PassCard关联状态
     * 4. 备份重要的历史数据
     * 
     * @param walletDTO 删除参数，包含钱包ID
     */
    public void delete(WalletDTO walletDTO);

    /**
     * 查询钱包详情
     * 
     * 功能说明：
     * - 查询钱包的完整信息
     * - 包含余额、地址、交易记录等
     * - 关联PassCard和Profile信息
     * 
     * @param wallet 钱包查询条件
     * @return WalletVO 钱包详细信息
     */
    WalletVO getDetail(Wallet wallet);

    public WalletVO getDefaultWallet(Wallet walletReq);

    public WalletAccount getWalletAccountByChainIdentifier(String chainIdentifier, String bizRoleTypeNo);

}
